Power Programmierung 2/Power-Programmierung CD 2 (Tewi)(1994).iso/gnu/gnulib/fchart/fchart.doc

Text File | 1994-06-05 | 24.0 KB | 722 lines

1 fchart
?
 FCHART is a simple command-driven utility to make bar and pie-charts.
 It should be treated as a previewer before using SAS(R). The program
 is based on the gnuplot v1.2 and 2.0.

 If you are a beginner, first read gnuplot documentation. Other useful
 hints can be found under the following topics:

 `gnuplot` - short comparision of fchart and gnuplot

 `environment` - about environment variables

 `general` - general description of available commands

 `notation` - notation used in this manual
2 notation
?notation
 NOTATION USED IN THIS MANUAL:
@start table
 page     - full-size page of paper or entire screen
 picture  - painted part of page, usually smaller
 /        - delimiter for synonyms of something
 ==       - as above, for whole expression
 { ... }  - optional argument
 |, *, +  - see regexp
 (!)      - something important not to be missed
 <pos>    - positive integer number (real will be truncated)
 <int>    - integer number (real will be truncated)
 <val>    - real number (value)
 <frac>   - fraction of some value (dep. on context):
            < 0  - error
            <0,1> - decimal fraction of value
            > 1  - per cent (%) of value
            thus 0.5 == 50, 70 == 70%, 1 == 100 (!),
            for values smaller than 1% use fraction (rare case),
            for values greater than 1 use %'s (200 == 2 times as ...)
 <range>  - range for several purposes. Two numbers in brackets with
            ":" as delimiter, eg [1:3], in relation first <= second.
            Syntax: '[' { <pos> } ':' { <pos> } ']'. First number
            if omitted is treated as zero (0), second omitted means
            "to infinity". Both numbers belong to the given range.
            (!) Omission works different than in Gnuplot.
#Notion & \  & Explanation \\ \hline
#page & - &full-size page of paper or entire screen \\
#picture & - & painted part of page, usually smaller \\
#/ & - & delimiter for synonyms of something \\
#== & - & as above, for whole expression \\
#\verb={ ... }= & - & optional argument \\
#\verb=|, *, += & - & see regexp \\
#(!) & - & something important not to be missed \\
#$<$pos$>$ & - & positive integer number (real will be truncated) \\
#$<$int$>$ & - & integer number (real will be truncated) \\
#$<$val$>$ & - & real number (value) \\
#$<$frac$>$ & - & fraction of some value (dep. on context): \\
#\ & \ & $<$ 0  - error \\
#\ & \ & $<$0,1$>$ - decimal fraction of value \\
#\ & \ & $>$ 1  - per cent (\%) of value \\
#\ & \ & thus 0.5 == 50, 70 == 70\%, 1 == 100 (!), \\
#\ & \ & for values smaller than 1\% use fraction (rare case), \\
#\ & \ & for values greater than 1 use \%'s (200 == 2 times as ...) \\
#$<$range$>$ & - & range for several purposes. Two numbers in brackets with \\
#\ & \ & `:' as delimiter, eg \verb=[1:3]=, in relation first $<=$ second. \\
#\ & \ & Syntax: \verb='[' { <pos> } ':' { <pos> } ']'=. First number \\
#\ & \ & if omitted is treated as zero (0), second omitted means \\
#\ & \ & 'to infinity'. Both numbers belong to the given range. \\
#\ & \ & (!) Omission works different than in Gnuplot. \\
%Notion@ @Explanation
%_
%page@-@full-size page of paper or entire screen
%picture@-@painted part of page, usually smaller
%/@-@delimiter for synonyms of something
%==@-@as above, for whole expression
%{ ... }@-@optional argument
%|, *, +@-@see regexp
%(!)@-@something important not to be missed
%<pos>@-@positive integer number (real will be truncated)
%<int>@-@integer number (real will be truncated)
%<val>@-@real number (value)
%<frac>@-@fraction of some value (dep. on context):
% @ @< 0  - error
% @ @<0,1> - decimal fraction of value
% @ @> 1  - per cent (%) of value
% @ @thus 0.5 == 50, 70 == 70%, 1 == 100 (!),
% @ @for values smaller than 1% use fraction (rare case),
% @ @for values greater than 1 use %'s (200 == 2 times as ...)
%<range>@-@range for several purposes. Two numbers in brackets with
% @ @`:' as delimiter, eg [1:3], in relation first <= second.
% @ @Syntax: '[' { <pos> } ':' { <pos> } ']'. First number
% @ @if omitted is treated as zero (0), second omitted means
% @ @'to infinity'. Both numbers belong to the given range.
% @ @(!) Omission works different than in Gnuplot.

@end table
2 fchart vs. gnuplot
?gnuplot
 Fchart uses the same language as gnuplot, though sometimes the
 meaning of a command/expression can be quite different (!). Fchart
 is data-oriented, thus has no built-in functions and does not perform
 any calculations. For gnuplot compatibility, complex numbers (in
 braces '{}') are accepted, but only their real part is used. Comments
 (#), semicolons(;) and line continuation with backslash (\) work in
 exactly the same way.

 Fchart uses GNUTERM environment variable. Fchart accepts only one
 command-line parameter (unlike Gnuplot (!))  -- type of terminal to
 run on. This has proven to be a good idea.
2 environment
?environment
 Fchart uses the same variables as gnuplot, except for FCHARTHELP,
 which can be defined as a path to the help file. On VMS, FCHART$HELP
 should be used instead.
 In additon, HOME directory is searched on startup for initial file
 called ".fchart" (or equivalent, see "start-up").
2 commands in general
?general
?terminal
?output
?size
?title
?zero
?clear
?exit
?quit
?help
?load
?pause
?replot
?redraw
?shell
?!
?test
?read
?set terminal
?set output
?set size
?set title
?set zero
 Several commands are directly taken from Gnuplot:
        clear
        exit/quit
        help/?
        load
        pause
        replot
        shell
        !
        test
 These commands are NOT described in this help.

 In addition, there are two synonyms:
        load/read
        replot/redraw

 Some other `set`-`show` parameters also have the same meaning:
        set terminal
        set output
        set size
        set title
        set zero
 and thus are NOT described here.
2 save
?save
 Syntax:
        save "filename" {{,} "string"}*
 Saves all current settings in the given file. This file can be used
 later with `load`/`read` command. Additional (optional) parameters
 are saved in the file as leading comments, one string per line.
?set pie

?set bar

2 set-show
?set
?show
 The `set` command sets LOTS of options. Type:
        set
 to get names of all possible parameters. The `show` commands shows
 their settings.  `show all` shows all the settings.

 In addition, `show` groups some related parameters; type:

        show general
 to see parameters used for any pictures

        show bar
 to see parameters affecting bar charts

        show pie
 to see parameters affecting pie charts

        show version
 to see the version of program you are working in.

 To get information about a parameter, type
        help <parameter name>
2 general parameters
3 parameters for input
4 range
?set range
?show range
?range
 Syntax:
        show range
        set range { <range> }
 (initial and default: `[ : ]`)

 Focuses input on a part of data file, within given range (incl.
 boundaries). Skips comments, and only proper values are counted.
 Lines are numbered starting from 0.
4 input (and input format)
?set input
?show input
?input
 Syntax:
        show input
        set input { gnuplot | private | customized }
 (initial and default: `private`)

 Sets global type of input files (this can be overriden for
 individual files, and all types can be freely mixed).

 Format of input files:

        gnuplot
 Accepts generic gnuplot files. Comments are skipped. Empty line
 produces "missing value". Only one number present is used as a value.
 If two are present, the second is treated as a value, and the first is
 taken as a label (for bar or slice). This produces stupidity for some
 data, but works well for other, date-oriented, like "Gnu population in
 Antarctica since 1965".

        private
 Reverse of gnuplot format: value, blank, label (optional).

        customized
 Accepts any fixed-field-length (e.g. SAS) files. No comments. Empty
 line produces error, and the standard form of missing value (spaces
 and dot) is supported. To describe required format use `set customized`
 command.
4 customized
?set customized
?show customized
?customized
 Syntax:
        show customized
        set customized { <range> { {,} <range> }}
 (initial and default: undefined)

 Sets ranges for value and (optional) for label: where should they be
 looked for in the line of data file? Ranges cannot overlap. Format is
 quite flexible (see description of ranges), and the only error occurs
 if the input line is shorter than that expected for given starting
 place of value. Characters are numbered from 0.
3 parameters for picture
4 frame
?set frame
?show frame
?frame
 Syntax:
        show frame
        set frame
        set noframe
 (initial: ON)

 Controls frame drawing. Frame is drawn around a page (!), not the
 picture.
4 offsets
?set offsets
?show offsets
?offsets
 Syntax:
        show offsets
        set offsets { <frac> {, <frac> {, <frac> {, <frac> }}}}
 (initial and default: 0,0,0,0)

 Sets the size and position of the picture on the page (!). Fractions
 are in terms of screen size and mean, respectively, left, right, top
 and bottom. Of course, it is necessary that left+right and bottom+top
 are less than 100%. E.g., to get the picture in the lower right corner
 of page, specify `set off 50, 0, 50, 0` == `set off 0.5, 0, 0.5, 0`.
 Offsets can be useful for piecharts with very long labels, since labels
 (as well as the picture title) can exceed given boundary (unlike graph
 itself).
4 logarithmic scale
?set logscale
?show logscale
?logscale
 Syntax:
        show logscale
        set logscale
        set nologscale
 (initial: OFF)

 Obvious. For logscale, all data entries must be > 0, as well as the
 base for bars.
4 highlighting
?set highlight
?show highlight
?highlight
 Syntax:
        show highlight
        set highlight { none | minim | maxim | <pos> }
 (initial and default: `none`)

 Sets global (!) highlighting, for all data. Highlighted element is
 drawn in a different color for bars or explodes for piecharts. Given
 number is just a number of element to be highlighted (in all the
 files), and refers, counting from 0, to _the first value read-in_ (!),
 not to the very first in the file . Can be also set individually for
 each file.
4 styles
?set style
?show style
?style
 Syntax:
        show style
        set style piechart | adjacent_bars | stacked_bars | layered_bars
 (initial: `adjacent_bars`)

 Sets the style of graph. Names are obvious, go and try.
4 arrows
?set arrow
?set noarrow
?show arrow
?arrow
 Syntax:
        show arrow { tag }
        set arrow { tag }
            { from {page|picture} <val>,<val> }
            { to {page|picture} <val>,<val> }
 (defaults: <first unused tag>, `picture` 0,0, `picture` 0,0)
        set noarrow { tag }
 (default: all arrows)

 This command allows you to add pointing arrows to the graph.
 The `tag` is an integer that is used to identify the arrow.
 If no tag is given, the lowest unused tag value is assigned
 automatically. The tag can be used to delete or change a specific
 arrow. To change any attribute of an existing arrow, use the `set
 arrow` command with the appropriate tag, and specify the parts of the
 arrow to be changed.

 All positions are denoted in any of two coordinate systems: either as
 real numbers <0,1> on the ideal drawing area <0,1>x<0,1>, or as an
 integers for virtual drawing board with resolution 100000x100000.

 Coordinates can refer to physical page or the picture being drawn.
 Arrows in the picture coordinate system follow the changes of the
 picture size and position (see `set offsets`), while those on the page
 are constant. An arrow can of course be drawn `from page` `to picture`
 and vice versa.

 See also `set line`.
4 lines
?set line
?set noline
?show line
?line
 Syntax:
        show line { tag }
        set line { <same syntax as for arrows> }
        set noline { tag }
 (defaults: see `set arrow`)

 This command allows you to draw an arbitrary line. Lines are in
 reality arrows without heads, and share with them the tag system.

 Also `show line` == `show arrow` and `set noline` == `set noarrow`.

 For more information, see `set arrow`.

 To change line to arrow, type:
        set arrow <tag of existing line>
 To change arrow to line, type:
        set line <tag of existing arrow>
3 parameters for printed text
4 format
?set format
?show format
?format
 Syntax:
       show format
       set format { "string" }
 (initial and default: "%g")

 Sets format for all numerical values printed on picture (!).
 Restrictions as in gnuplot. This is a very important parameter for
 labeling -- if that doesn't work correctly, change format. Further
 information can be found in the gnuplot manual.
4 font
?set font
?show font
?font
 Syntax:
        show font
        set font { never | when_needed | rotated | always }
 (initial: `when_needed`)
 (default: `always`)

 Sets usage of built-in vector font:
@start table
   always, never - obvious
   when_needed   - font is used when printed text:
                   * should fit within the given boundary
                   * is to be rotated, and terminal can't do that
   rotated       - as `when_needed`, but _always_(!) for rotated text;
                   useful for some terminals, like 'regis' and 'latex'
#Value & \ & Meaning \\ \hline
#\verb=always=, \verb=never= & - & obvious \\
#\verb=when_needed= & - & font is used when printed text: \\
#\ & \ & * should fit within the given boundary \\
#\ & \ & * is to be rotated, and terminal can't do that \\
#\verb=rotated= & - & as \verb=when_needed=, but \_always\_ (!) for rotated text; \\
#\ & \ & useful for some terminals, like 'regis' and 'latex' \\
%Value@ @Meaning
%always, never@-@obvious
%when_needed@-@font is used when printed text:
% @ @* should fit within the given boundary
% @ @* is to be rotated, and terminal can't do that
%rotated@-@as 'when_needed', but _always_ (!) for rotated text;
% @ @useful for some terminals, like 'regis' and 'latex'

@end table
4 truncate
?set truncate
?show truncate
?truncate
 Syntax:
        show truncate
        set notruncate
        set truncate { <pos> }
 (initial: OFF)
 (default: 0)

 Sets maximal length for labels from data files. Command `set truncate`
 will simply ignore all the user labels (see also `set autolabeling`).
4 autolabeling
?set autolabeling
?show autolabeling
?autolabeling
 Syntax:
        show autolabeling
        set autolabeling
        set noautolabeling
 (initial: OFF)

 Labels read from data files are striped, i.e. all leading and
 trailing spaces are _always_ removed. If all labels are undefined, and
 this parameter is ON, program will generate numbers starting with the
 number of the first read element (i.e. left boundary from `set
 range`). Rules for multiple elements (e.g. one stack or one column in
 "layered style") are different:

 - all undefined : autogenerate (if ON)

 - all the same (with some undefined) : draw (one of) them

 - different : nothing is drawn
4 labels
?set label
?set nolabel
?show label
?label
 Syntax:
        show label { <tag> }
        set nolabel { <tag> }
 (default: all labels)
        set label { <tag> } { "text" }
            { left | centre | right }
            { at {page|picture} <val>,<val> }
            { height <val> }
            { width <val> }
            { horizontal | vertical |
              direction left | right | up | down |
              west | east | south | north |
              rotation <val> }
 (defaults: <first unused tag>, "", `left`, at `picture` 0,0,
 height 0, width 0, `horizontal`)

 This command places a label on the graph. Here is a brief description
 of the parameters:

 `<tag>` -- integer to identify a label. See also `set arrow`.

 "text" -- text of the label. Defaults to empty: "".

 The third parameter sets desired justification of the label around
 its position. This parameter can be put also _after_ `at` phrase.

 `at` phrase gives the position for the label. For the exact meaning
 of its subparts, see `set arrow`.

 `height` and `width` specify desired height and width of text.
 Unfortunately, text cannot be stretched, so only one of them should be
 given. If both are set, text will be no higher than `height` and no
 wider than `width`, but nothing more is certain.
 Values of `height` and `width` refer to the page or picture, in
 accordance with the `at` phrase. Exact meaning of values for both is
 the same as for positions (see `set arrow`).
 Note: both values refer to the resulting size of character bounding
 box, not character itself (boundig box is 30% higher and 20% wider).

 The last parameter specifies desired direction the text should be
 drawn in. The names are obvious, and `rotation` is an arbitrary angle
 in radians (positive angle counts counterclockwise).

 Rules for using fonts with labels:
@start table
       ----------------------------------------------
       | height & width & direction   ==> font      |
       ----------------------------------------------
       |    both  0     | horizontal,  | follows    |
       |                | east, right, | common     |
       |                | vertical,    | rules by   |
       |                | up, north    | `set font` |
       ----------------------------------------------
       |      any       | other than   | built-in   |
       |                | above        | vector f.  |
       ----------------------------------------------
       | given one of   |     any      | built-in   |
       | them or both   |              | vector f.  |
       ----------------------------------------------
# height \& width & direction & resulting font \\ \hline
# both 0 & horizontal, east, right, & follows common rules \\
# \      & vertical, up, north & given by \verb=set font= \\ \hline
# any    & other than above & built-in vector font \\ \hline
# given any of them & any & built-in vector font \\
%height & width @ direction @ resulting font
%_
%both 0 @ horizontal, east, right, @ follows common rules
%       @ vertical, up, north @ given by "set font"
%_
%any    @ other than above @ built-in vector font
%_
% given any of them @ any @ built-in vector font
@end table
2 settings for bars
3 autoscale
?set bar autoscale
?show autoscale
?autoscale
 Syntax:
        show autoscale
        set bar autoscale
        set bar noautoscale
 (initial: ON)

 Controls rounding and drawing of axes for bars. Check it. Axes are
 drawn on the left side of bars, looking from base. There's no way to
 change ticking and naming the axis. Ticking algorithm is not very
 clever, although it will never overlap ticking labels.
3 base
?set bar base
?show base
?base
 Syntax:
        show base
        set bar base { <val> }
 (initial and default: 0)

 Sets base for bars. Should be 0 for stacked ones and at least 1 for
 logscale ON. Sometimes useful, though eats a lot of code.
3 clockwise
?set bar clockwise
?show clockwise
?clockwise
 Syntax:
        show clockwise
        set bar clockwise
        set bar counter_clockwise
 (initial: `clockwise`)

 Direction for drawing bars. "Clockwise" means left to right looking
 from base. Useful for strange gravitation.
 Parameter for pies -- painfully obvious.
3 gravitation
?set bar gravitation
?show gravitation
?gravitation
 Syntax:
        show gravitation
        set bar gravitation { left | top | right | bottom }
        set bar gravitation { west | north | east | south }
 (initial and default: `bottom`/`south`)

 Sets gravitation for bars, i.e. on what side base should be drawn.
 That is different from just turning page to the left or right.
3 width
?set bar width
?show width
?width
 Syntax:
        show width
        set bar width { <frac> {, <frac> {, <frac> }}}
 (initial and default: 0.2, 0.2, 0.5)

 Sets bar parameters: maximal allowable width (as a fraction of
 picture size), space between bars and space between groups of bars
 (last two as a fraction of bar width chosen by program), respectively.
 If counted bar width is bigger than allowable, this value is taken and
 a smaller graph is centered within picture. There is no way to set the
 standard bar width, determined by picture size and number of bars.
2 settings for pies
3 clockwise
?set pie clockwise
?show clockwise
 Syntax:
        show clockwise
        set pie clockwise
        set pie counter_clockwise
 (initial: `clockwise`)

 Obvious.
3 explode
?set pie explode
?set explode
?explode
 Syntax:
        show explode
        set pie explode { <params as for bar gravitation> }
 (initial and default: random)

 Sets direction of exploding slice (if highlighting != none).
 Obvious. "Random" means that pie is drawn from top, and a slice will
 explode "outside", just where it should and can.
3 radius
?set pie radius
?show radius
?radius
 Syntax:
        show radius
        set pie radius { <frac> }
 (initial and default: 0.3)

 Sets exploding distance (!) for hightlited slice -- as a fraction
 of the pie radius. Radius depends on the picture size and exploding
 distance, and there is no way to change it.
3 sample
?set pie sample
?show sample
?sample
 Syntax:
        show sample
        set pie sample <pos>
 (initial: 160)

 Number of samples for drawing arcs. Depends on screen resolution.
3 threshold
?set pie threshold
?show threshold
?threshold
 Syntax:
        show threshold
        set pie threshold { <frac> { "name" }}
 (initial and default: 0, "other")

 Threshold for combining slices that are too small into one. Expressed
 as a fraction of whole pie (i.e. 360 deg or 2Pi rad). Must be < 100.
 If highlighting is != none, sices are not combined (!). Combined slice
 is labeled with the given "name".
2 getting picture -- plot command
?plot
?draw
?tplot
?tdraw
 There are 6 commands to do that, but in two ways only:
        plot/draw
        tplot/tdraw/trans_plot/trans_draw

 They differ in treating incoming values:

 * In `plot`, data from one file create one unit (pie, layer, stack or
 group, depending on style).

 * In `tplot`, one unit is created from many files, thus first value
 from all the files forms one unit, second value next one, and so on.
 It is just like trasposition of data matrix, and hence the name.

 Of course, files need not be the same length, since units can be of
 different size. Files can be of different input style, also.

 Full syntax:
        plot/tplot
            { <range> }
            { (style) } "filename"
                { as "name" }
                { highlighting <type of highlighting> }
            { , <same syntax as above> }*

 where :
 `range` overrides `set range` (permanently (!)),
 `style` is the name of style in parenthesis (which means that though
 styles can be freely mixed, only one customized style can be used at
 once -- this limitation probably should be changed), e.g. "(gnu)",
 `as` phrase gives the label to be used instead of filename, and
 `highlighting` sets _local_ highlighting (bogus for `tplot`).

 Note: to turn off highlighting, `none` must be specified explicitly.
2 start-up
?startup
?start
?.fchart
?fchart.ini
 When fchart is run, it looks for an initialization file to load.
 This file is called `.fchart` on Unix , and `FCHART.INI` on other
 systems.  If this file is not found in the current directory, the
 program will look for it in your home directory (under MS-DOS, the
 environment variable `FCHART` should contain the name of this
 directory).

 If this file is found, fchart executes the commands in this file.
 This is most useful for setting your terminal type and other
 parameters.

 By default, output is sent to "stdout", and thus can be redirected.
 All messages go to "stderr".
2 bugs
?bugs
 Lots of, probably. The most important is wrong bar centering.